An example document

Download the demo project from Github

A standard workflow

A Quarto workflow

Solution: Use a Quarto workflow everything (code, text, metadata) in one place. Let Quarto do the magic

The basic Quarto workflow

1. Create a .qmd document
2. Write the document

• text that e.g. introduces you topic, interprets your results, …
• code (R, Python, Julia) that produces numbers, figures, tables, …
• metadata that defines how the result should look like (e.g. which output format)

3. Render the document to a defined output format (e.g. PDF) using Quarto

Step 1 - Create the document

Open R Studio and go to File -> New File -> Quarto Document

Just click Create and the file will open in R Studio.

In other environments you can just create and empty file with .qmd ending

Step 2 - Write the document

Step 3 - Render the document

Step 3 - Render the document

What happens during rendering?

Artwork from “Hello, Quarto” keynote by Julia Lowndes and Mine Çetinkaya-Rundel,presented at RStudio Conference 2022. Illustrated by Allison Horst.

The text body - Markdown

• Markdown is a simple markup language to create formatted text

The text body - Markdown

If you don’t want to use markdown, there is a really nice feature in R Studio: The visual editor.

The visual editor

Convenient, word-like interface for formatting text and adding features.

The visual editor

Using the visual editor, makes many things that would be painful in Markdown really easy.

My favorite feature in the visual editor:

• Add citations (Insert -> Citation) from Zotero library, DOI search, PubMed, …

The Code

Code can be included in code chunks as inline code

• Code chunks can contain any type of R/Python/Julia code
• Code is (by default) executed and output is included in document
  • Text output
  • Figures
  • …

The Code

Inline code starts and ends with 1 backtick

`r `

The mean of the values 1, 2 and 3 is `r mean(1:3)`

The Code

Code chunks starts and ends with 3 backticks

```{r}
library(ggplot2)
ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess")
```

```{python}
import numpy as np
import matplotlib.pyplot as plt

r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(subplot_kw = {'projection': 'polar'})
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()
```

The Code

Insert a code chunk

• Insert a code chunk by going to Code -> Insert chunk

• Use the keyboard shortcut Ctrl + Alt + I / Cmd + Option + I

• Inline chunks have to be typed or use the </> symbol in visual mode

The Code

Run code chunk

• Code chunks are evaluated by knitr when rendering the document

• Code chunks can also be run like normal R code

• Run Code chunk by clicking on the green arrow next to the chunk

The code

Code chunk have special comments that start with #|, e.g.

```{r}
#| label: fig-airquality
#| fig-cap: Temperature and ozone level.
#| include: false

library(ggplot2)

ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess")
```

• label: Figure and chunk label that can be referred to in text
• fig-cap: Figure caption
• include: Include the output (i.e. the plot) in the document but don’t show the code

Include image via code chunk

Include an image from a code chunk via knitr::include_graphics().

```{r}
#| echo: false
#| out.width: "20%"
#| fig-align: center
#| fig-cap: Quarto logo
#| fig-cap-location: margin
knitr::include_graphics("images/2023_05_11_quarto/quarto_straight.png")
```

Quarto logo

YAML header

---
title: "My first document"
subtitle: "Whatever subtitle makes sense"
author: "Selina Baldauf"
date: "`r Sys.Date()`"
---

YAML header

For document output formats

---
title: "My first document"
author: "Selina Baldauf"
date: "`r Sys.Date()`"
format: html
---

---
title: "My first document"
author: "Selina Baldauf"
date: "`r Sys.Date()`"
format: 
  html: default
  pdf: default
  docx: default
---

YAML header

Execute options

• Default options for code chunks
• Can be overwritten by local comments in code chunks

---
title: "My first document"
author: "Selina Baldauf"
date: "`r Sys.Date()`"
format: html
execute: 
  echo: false
  warning: false
---

References for all the elements

Summary

• Quarto can combine formatted text and code to create reproducible documents

Outlook

Quarto offers many more things like:

• Presentations (Powerpoint or Revealjs/HTML)
• Websites
• Easily publish your documents or websites on quartopub or Github
  • See here for more information
• Control the rendering process via R scripts using quarto::quarto_render()
• Parameterized reports

Next lecture

Version control with Git

Git is an essential skill if you use any programming language. It allows you to keep track of changes over time, collaborate with others, and maintain a clear and organized file structure. This can save time, improve research efficiency, and makes it easy to publish your code.

Thank you for your attention :)

Questions?

“Artwork from”Hello, Quarto” keynote by Julia Lowndes and Mine Çetinkaya-Rundel, presented at RStudio Conference 2022. Illustrated by Allison Horst.”